|
|
This Technical Note describes, in detail, the local and global script variables.
[Jun 01 1989]
|
Introduction
The Script Manager maintains a number of global variables which can be read
with the routine _GetEnvirons. These variables can be set by a
corresponding routine, _SetEnvirons. In addition, each script
interface system maintains variables of its own. These are referred to as
local variables in Inside Macintosh, Volume V-293, The Script Manager, and are
read by _GetScript and set by _SetScript.
Think of it like this: the Script Manager maintains an environment in which
different script interfaces can run. The global variables are used to set up
and maintain the environment (thus the names for the routines
_GetEnvirons and _SetEnvirons), and the local variables
control how the script itself works (so we have _GetScript and
_SetScript).
Back to top
Global Variables
When you call _GetEnvirons or _GetScript, you describe the
variable you are interested in with a verb. A verb is simply an integer
constant which the Script Manager uses to figure out which variable you want to
read or set. The z in Inside Macintosh, V-313, gives incorrect names
and descriptions for some of the _GetEnvirons and
_SetEnvirons verbs. Table 1 provides correct descriptions.
Table 1. Verbs for _GetEnvirons and _SetEnvirons
The descriptions in the table are still a bit sketchy. The next section
describes each variable in more detail and describes the size of each global.
Byte or word globals are mapped to the low-order byte or word of the
LongInt returned by _GetEnvirons, with the high-order parts
set to zero. Similarly, for these globals _SetEnvirons ignores all but
the appropriate part (low-order byte or word) of its params value.
Verb Name Bytes Brief Description
smVersion 2 Script Manager version number
At boot time, the version global is initialized to the value SMgrVers.
The high byte is the major version number and is defined in the MPW interface
files. The low byte is updated when any changes are made to the Script
Manager.
smMunged 2 Global modification count
The munged global is initialized to zero at boot time and incremented when:
_KeyScript changes the key script and updates smKeyScript and smLastScript_SetEnvirons is used to change a Script Manager global
smEnabled 1 Script count; 0 if Script Manager not enabled
At boot time or switch-launch time, the enabled global is initialized to zero,
then incremented for each script that is installed and enabled. Since the
Roman script system should always be installed by the Script Manager, a value
of zero indicates that the Script Manager is not enabled.
It should be noted that older versions of the Script Manager treated this as a
Boolean. In other words, if there was more than one script installed,
_GetEnvirons(smEnabled) would return 255 (when _GetEnvirons
returns a Boolean value $FF represents true).
For this reason, when testing to see if more than one script is installed, it
is best to test as follows:
scriptsinstalled := GetEnvirons(smEnabled);
IF scriptsinstalled > 1 THEN
|
smBidirect 1 Bidirectional script flag
The bidirectional global indicates that at least one bidirectional script is
installed. It should be set to true ($FF) by the Arabic and Hebrew script
systems. This is not presently done, but will be corrected in future versions
of these systems.
smFontForce 1 Force font flag
smIntlForce 1 Force international utilities flag
smForced 1 Current script forced to system script
smDefault 1 Current script defaulted to Roman script
At boot time, FontForce and IntlForce are set from the
'itlc' resource, and Forced and Default are set to
zero. These are all flags with the value zero for false and $FF for true.
FontForce and IntlForce control the operation of the
_FontScript, _Font2Script, and _IntlScript routines.
Forced and Default report the actions of these routines.
Setting FontForce to true forces Roman fonts to be interpreted as
belonging to the system script. This is for compatibility with applications
that hard-code font numbers.
IntlForce determines the behavior of the _IUGetIntl call. When
intlforce is set to true, _IUGetIntl will return a handle to
the international resources (of type 'itlx' where x is 0-2)
for the system script. When IntlForce is false, the
_IUGetIntl will use the font of the current port to determine the
appropriate resources to fetch. Thus date formats, sorting, etc. can reflect
the current script.
smPrint 4 Print action vector
Print action routine vector; set up at boot time. See M.TE.PrintAction.
smSysScript 2 Preferred system script
smLastScript 2 Last keyboard script
smKeyScript 2 Keyboard script
At boot time and switch-launch time, SysScript and KeyScript
are set from the SysScript field of the 'itlc' resource if
that script is installed and enabled; otherwise, SysScript and
KeyScript are set to Roman (without setting Default).
The KeyScript global is the current keyboard script, tested and
updated by the _KeyScript routine. When _KeyScript changes
KeyScript, it moves the old value to LastScript.
_KeyScript can also swap the current key script with the last one,
which it retrieves from LastScript. The KeyScript value is
also used to get the proper keyboard script icon and to retrieve the proper
'KCHR'.
SysScript specifies the system script, and is used, for example, by
_FontScript, _Font2Script, and _IntlScript.
KeyScript, LastScript, and SysScript always contain
integers that correspond to a script number. Script numbers are documented in
The Script Manager chapter of Inside Macintosh, Volume V-293.
smSysRef 2 System folder volRefNum
Set from the global BootDrive at boot time and switch-launch time.
SysRef was originally a way of testing for vanilla launch versus
switch launch; now the Enabled global is used for that purpose.
smKeyCache 2 [Obsolete, do not use]
smKeySwap 4 Keyboard swapping resource handle
The 'KSWP' resource handle is put here at boot time and switch-launch
time. A 'KSWP' resource contains a table of key sequences that will
cause the currently installed 'KCHR' (keyboard mapping table) to
change to the preferred system 'KCHR', switch to the Roman
'KCHR', or rotate among the available 'KCHR' resources. The
table includes the virtual key code and the modifier keys. The following is
the 'KSWP' resource for the Kanji script interface system.
resource 'KSWP' (0, sysheap) {
{/* array: 3 elements */
/* [1] */
Rotate, 49, controlOff, optionOff, shiftOff, commandOn,
/* [2] */
System, 70, controlOff, optionOff, shiftOff, commandOn,
/* [3] */
Roman, 66, controlOff, optionOff, shiftOff, commandOn
}
|
The resource says rotate 'KCHR' resources if a Space-Command key
occurs, switch to the system 'KCHR' on keypad plus (+)-Command key,
and switch to the Roman 'KCHR' on keypad asterisk (*)-Command key.
smGenFlags 4 General flags
Only the two high-order bits are defined (in the file ScriptEqu.a), as
follows:
smfShowIcon = 31 (show icon even if only one script)
smfDualCaret = 30 (use dual caret for mixed direction text)
The high-order byte of smgrGenFlags, containing these flags, should be
setup from the flags byte in the 'itlc' resource. This is
not presently done, but will be fixed in future versions of the Script
Manager.
The following MPW Pascal procedure demonstrates how to get script
'SICN' resources to display even if there is only one script system
installed.
PROCEDURE SetSICN;
VAR
SICNstate: Longint;
err: Oserr;
BEGIN
SICNstate := GetEnvirons(smGenFlags);
BSET(SICNstate,smfShowIcon);
err := SetEnvirons(smGenFlags,SICNstate);
|
smOverride 4 Script override flags
At present, this is not set or used by the Script Manager. It is, however,
reserved for future improvements.
smCharPortion 2 Ch vs Sp Extra proportion, 4.12 fixed
This is 16-bit fixed-point value in 4.12 format (e.g., 10% = $0199). It is
initialized to 10 percent at boot time. It is intended to be used by script
systems to allocate space among intercharacter spacing and interword spacing
when justifying text.
A 16-bit fixed-point value in 4.12 format is similar to the fixed-point number
type defined on page I-79 of Inside Macintosh . The obvious difference
being that it is only 16 bits long. The integer part of the value is stored
in the high four bits, and the fractional part is stored in the low 12 bits.
16-bit Fixed-Point Number in 4.12 format
Back to top
Local Variables
Every script interface system has local variables. Page V-132 of Inside
Macintosh lists verbs which are constants that indicate which variable you
want to read or set. The table of constants used to access the local variable,
although more accurate than the global table, does contain a few inaccuracies.
In addition four new constants have been added. Table 2 gives the correct
constants.
Table 2. Local Variable Constants
Here again the descriptions are a little terse. The following section
describes each variable in more detail and describes the size of each
variable.
Verb Name Bytes Brief Description
smScriptVersion 4 Script Interface version number
When the script interface is loaded, this is set to the current version
number.
smScriptMunged 2 Local modification count
This variable is incremented each time _SetScript is called.
smScriptEnabled 1 Script Enabled Flag
A Boolean which indicates whether the script has been enabled. Set to
$FF when enabled and zero when not enabled.
smScriptRight 1 Right to Left Flag
A Boolean indicating if text should be drawn right to left or left to
right. It is set to $FF for right to left text (Arabic and Hebrew scripts) and
zero for left to right (Roman).
smScriptJust 1 Justification Flag
A byte flag which describes how text should be justified. The possible
settings correspond to the justification flags used by TextEdit.
0 = left justification
1 = center justified
-1 = right justified
|
smScriptRedraw 1 Word Redraw Flag
A byte flag describing how much of a line should be redrawn when text is being
entered.
0 Only draw a character
1 Redraw the entire word
-1 Redraw the entire line (Arabic)
|
smScriptSysFond 2 Preferred System Font
This is the font family ID for the preferred System Font. In a Roman system,
ScriptSysFond is 0, the family ID for Chicago.
smScriptAppFond 2 Preferred Application Font
Font family ID for the preferred Application Font. In a Roman system,
ScriptAppFond is 3, the family ID for Geneva.
smScriptNumber 4 Script 'itl0' ID
Resource ID of 'itl0' for this script. The 'itl0' resource
describes how numbers and times should be displayed. The resource ID should
match the country version code for a given country.
smScriptDate 4 Script 'itl1' ID
Resource ID of the 'itl1' for this script. The 'itl1'
describes how dates should be displayed.
smScriptSort 4 Script 'itl2' ID
Resource ID of the 'itl2' for this script. The 'itl2'
contains routines for sorting. See M.TE.NewStringComp.
smScriptFlags 2 Script flags
This verb provides access to the script flags word, which contains bit flags
that describe features of the script. This word is initialized from the
script's 'itlb' resource. Constants specifying the bit numbers are
described in Table 3.
Table 3. Constant Bit Numbers
smScriptToken 2 Script 'itl2' ID
Resource ID of the 'itl4' for this script. The 'itl4'
contains contains tables needed by the number formatting and conversion
routines and the _intlTokenize routine. See Script Manager 2.0,
Interim Chapter.
smScriptRsvd 4 Reserved
smScriptLang 2 Script's language code
This verb accesses a word which contains the current language code for the
script. The language codes are defined in the MPW interface files.
smScriptNumDate 2 Number and date representation codes
This verb accesses a word containing the number and date representation codes
for the script. The number representation code is in the high byte of the
word, and the date code is in the low byte.
The possible values for number representations and date codes are declared as
constants in the MPW interface files.
The number codes are: and the date codes are:
intWestern = 0; calGregorian = 0;
intArabic = 1; calArabicCivil = 1;
intRoman = 2; calArabicLunar = 2;
intJapanese = 3; calJapanese = 3;
intEuropean = 4; calJewish = 4;
calCoptic = 5;
|
smScriptKeys 4 Script 'KCHR' ID
Resource ID of preferred 'KCHR' resource. The 'KCHR' resource is used to map
virtual key codes into the correct character code. See M.TB.KeyMapping.
smScriptIcon 4 Script 'SICN' ID
Resource ID of the small icon that is used to represent which country specific
resources ('itl0', 'itl1', 'itl2', 'KCHR')
are currently installed in the system. Presently, the Roman system does not
display the 'SICN'. Arabic, Kanji, Chinese, and Hebrew interface
systems do display this icon in the upper-right corner of the menu bar.
smScriptPrint 4 Script printer action routine
Print action routine vector; setup when script is installed by Script Manager.
See M.TE.PrintAction.
smScriptTrap 4 Trap entry pointer
Pointer to Script dispatch routine. Script Manager routines always belong to
one of two groups. The first group of routines are common to every script
interface system, and the second group must be supplied by the script interface
system. This variable will point to a dispatch routine for the
interface-supplied routines. When you call _ScriptUtil, it looks at
the selector that is passed and either calls a common routine or calls the
routine whose address is stored in ScriptTrap. The routine in
smScriptTrap will then use the selector to vector to the correct
routine. In general, routines that display or measure text in some way will be
supplied by the interface.
A list at the end of this Note indicates which routines are implemented by the
Script Manager and which routines are supplied by a script interface system.
smScriptCreator 4 Script file creator
The four character creator type for the script interface's file. For Roman it
is "ZSYS," the same creator as any system file has.
smScriptFile 4 Script file name
A pointer to the a Pascal string which contains the name of the file containing
the script interface system. For the Roman SIS, it is System.
smScriptName 44 Script name
A pointer to a Pascal string which contains the script interface's name. For
Roman it is naturally, "Roman."
Back to top
Who Does What?
Table 4 breaks the documented routines into common Script Manager routines and
interface specific routines.
Table 4. Script Manager Routines and Interface Specific Routines
_GetScript and _SetScript, which return the values of local
script variables, are implemented by the Script Manager for some verbs and the
script interface system for others.
There is also a group of Script Manager routines which don't use the
_ScriptUtil trap, but are documented in The Script Manager chapter of
Inside Macintosh, Volume V-293 or The Script Manager 2.0 Interim
Chapter. There routines are utilities that read and write to low-memory or
PRAM. It is important to use these routines when they are available. That
will allow Apple to modify where global variables, etc. are stored, and your
application will remain compatible. The utilities are:
GetDefFontSize
GetSysFont
GetAppFont
GetMBarHeight
GetSysJust
|
|
ReadLocation (documented in Interim Chapter)
WriteLocation (documented in Interim Chapter)
Back to top
References
M.TB.KeyMapping
M.TE.ScriptManagerPrintAction
Back to top
Downloadables
|
|
Acrobat version of this Note (44K).
|
Download
|
| 
